Skip to content

feat(paperclip-plugin): add paperclip-plugin-hindsight Paperclip plugin#918

Closed
benfrank241 wants to merge 2 commits into
mainfrom
feat/paperclip-plugin
Closed

feat(paperclip-plugin): add paperclip-plugin-hindsight Paperclip plugin#918
benfrank241 wants to merge 2 commits into
mainfrom
feat/paperclip-plugin

Conversation

@benfrank241

Copy link
Copy Markdown
Member

Summary

  • Adds paperclip-plugin-hindsight — a proper Paperclip plugin (with manifest + worker) that gives all Paperclip agents persistent long-term memory via Hindsight
  • Installable via pnpm paperclipai plugin install paperclip-plugin-hindsight
  • 15 tests, all passing

What It Does

Trigger Action
agent.run.started Recalls relevant memories (keyed to issue title + description), caches in plugin.state scoped to the run
agent.run.finished Auto-retains agent output to Hindsight (with runId as document ID)
hindsight_recall tool Agents call mid-run to query memory — returns cached state first, falls back to live recall
hindsight_retain tool Agents call to store facts immediately during a run
onValidateConfig Tests Hindsight connectivity when operator saves config

Bank ID Format

Memory is keyed to companyId + agentId, never to the ephemeral run ID:

paperclip::{companyId}::{agentId}    ← default
paperclip::{companyId}               ← company granularity
paperclip::{agentId}                 ← agent granularity

Architecture

hindsight-integrations/paperclip-plugin/
├── src/manifest.ts   # PaperclipPluginManifestV1 (capabilities, tools, config schema)
├── src/worker.ts     # definePlugin() — events + tools
├── src/client.ts     # Hindsight HTTP client (native fetch, no deps)
├── src/bank.ts       # Bank ID derivation from companyId/agentId
└── tests/plugin.spec.ts  # 15 tests using @paperclipai/plugin-sdk createTestHarness

Note

This is distinct from the existing hindsight-integrations/paperclip/ npm library. That library is a developer utility for HTTP adapter agents. This is a proper Paperclip plugin that works with all adapter types (Claude, Codex, Cursor, HTTP, Process) via the event system.

Adds a proper Paperclip plugin package (paperclip-plugin-hindsight) that
gives all Paperclip agents persistent long-term memory via Hindsight.

Unlike the existing hindsight-paperclip npm library (which is a developer
utility), this is a proper Paperclip plugin with a manifest, worker, and
SDK integration — installable via:
  pnpm paperclipai plugin install paperclip-plugin-hindsight

What it does:
- agent.run.started: recalls relevant memories, caches in plugin state
- agent.run.finished: auto-retains run output to Hindsight
- hindsight_recall tool: agents query memory mid-run (uses cache first)
- hindsight_retain tool: agents store facts mid-run
- onValidateConfig: tests connectivity to Hindsight on config save

15 tests, all passing.
@benfrank241

Copy link
Copy Markdown
Member Author

Closing in favor of #2
934

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant